===============================================================================
 3CX BULK MANAGER - HOW TO RUN
 Bulk Holiday & Office Hours Management for 3CX v20
===============================================================================

This program is not an .exe - it runs using Python, which is free. You only
need to install Python once. After that, starting the program takes about
five seconds.

Total setup time: about 5 minutes.

If you get stuck, jump to the TROUBLESHOOTING section at the bottom. Nearly
every problem is one of the four listed there.


-------------------------------------------------------------------------------
 STEP 1 - INSTALL PYTHON  (one time only)
-------------------------------------------------------------------------------

1. Go to:

       https://www.python.org/downloads/

2. Click the big yellow "Download Python" button at the top of the page.
   You need version 3.10 or newer. The button always offers the latest
   version, so it will be fine.

3. Run the installer you just downloaded.

4. *** THIS STEP IS THE ONE PEOPLE MISS ***

   On the very first screen of the installer, at the BOTTOM, there is a
   checkbox that says:

       [ ] Add python.exe to PATH

   TICK THAT BOX before you click anything else.

   If you skip it, Windows will not be able to find Python later and you
   will get a "not recognized" error in Step 3. If you have already
   installed Python without ticking it, just run the installer again and
   choose "Modify".

5. Click "Install Now" and wait for it to finish. Click Close.


-------------------------------------------------------------------------------
 STEP 2 - OPEN A COMMAND PROMPT IN THIS FOLDER
-------------------------------------------------------------------------------

The easy way:

1. Open File Explorer and navigate to the folder containing this file
   (the folder with "main.py" in it).

2. Click once in the ADDRESS BAR at the top - the bar showing the folder
   path. The path will highlight in blue.

3. Type over it:

       cmd

4. Press Enter.

A black command prompt window opens, already pointing at the right folder.
The last line will show the folder path followed by a ">" symbol.

The manual way (if the above does not work):

   Press the Windows key, type "cmd", press Enter, then type "cd" followed
   by a space and the full path to this folder in quotes. For example:

       cd "C:\Users\YourName\Downloads\3CX Bulk Manager 1.1"


-------------------------------------------------------------------------------
 STEP 3 - INSTALL THE REQUIRED COMPONENTS  (one time only)
-------------------------------------------------------------------------------

In the command prompt window from Step 2, type this line exactly and press
Enter:

       py -m pip install -r requirements.txt

You will see several lines of text scroll past as it downloads four
components. This takes 30-60 seconds and needs an internet connection.

When it finishes you will see "Successfully installed ..." and get your
">" prompt back. You never have to do this step again.


-------------------------------------------------------------------------------
 STEP 4 - RUN THE PROGRAM
-------------------------------------------------------------------------------

In the same command prompt window, type:

       py main.py

Press Enter. The program window opens.

That is it. From now on, starting the program is just Step 2 followed by
Step 4 - open the folder, type cmd, type "py main.py".

Leave the black command prompt window open while you use the program.
Closing it closes the program. If something goes wrong, any error message
appears in that black window, which is useful to copy if you need help.


-------------------------------------------------------------------------------
 MAKING A SHORTCUT  (optional, but handy)
-------------------------------------------------------------------------------

To avoid typing commands every time:

1. Right-click inside this folder and choose New > Text Document.
2. Open it and paste in this single line:

       py main.py

3. Save it, then close it.
4. Rename the file from "New Text Document.txt" to:

       Start.bat

   Windows will warn you about changing the file extension - click Yes.
   (If you cannot see the ".txt" part of the name, open File Explorer, go
   to the View menu, and tick "File name extensions".)

Now you can just double-click "Start.bat" to launch the program.


-------------------------------------------------------------------------------
 FIRST TIME USING THE PROGRAM
-------------------------------------------------------------------------------

1. On the first screen, choose Wizard Mode (guided, recommended to start)
   or Advanced Mode (everything visible at once).

2. Add your 3CX system. You will be asked for:

     - A display name    - anything you like, e.g. "Head Office"
     - Hostname          - e.g. pbx.my3cx.us
                           Do NOT include "https://" or a trailing slash.
                           If your system uses a custom port, include it,
                           e.g. pbx.my3cx.us:5001
     - Username          - your 3CX admin extension number or email
     - Password          - your 3CX admin password

3. Click Connect.

4. If your 3CX system uses two-factor authentication, you will be asked for
   the 6-digit code from your authenticator app. You only need to do this
   ONCE per system - the program then remembers the session for about 60
   days, so day-to-day use will not ask you again.

The program needs an internet connection to reach your 3CX system and to
look up public holiday dates.


-------------------------------------------------------------------------------
 A NOTE ON YOUR CREDENTIALS
-------------------------------------------------------------------------------

When you add a system, the program creates a file called "config.json" in
this folder to remember it. Your username and password are scrambled before
being saved, but this is convenience, not strong security.

A second file, "session_cache.json", stores your logged-in session so you
are not asked for a two-factor code every time.

DO NOT share, email, or upload either of these two files. Anyone who has
them may be able to reach your phone system. They are yours alone - they are
never included when this program is packaged up for distribution.


===============================================================================
 TROUBLESHOOTING
===============================================================================

 "py is not recognized as an internal or external command"
-------------------------------------------------------------------------------
 Python is not installed, or the "Add python.exe to PATH" box in Step 1 was
 not ticked.

 Fix: run the Python installer again, choose "Modify", and make sure the
 PATH option is enabled. Then CLOSE the command prompt window and open a
 new one - it only picks up the change on a fresh window.

 Still stuck? Try "python main.py" instead of "py main.py".


 "ModuleNotFoundError: No module named 'customtkinter'"
-------------------------------------------------------------------------------
 (Or 'requests', 'openpyxl', or 'cryptography'.)

 Step 3 was skipped, or did not finish successfully. Go back and run:

       py -m pip install -r requirements.txt

 Watch for the word "Successfully" at the end.


 "can't open file 'main.py': [Errno 2] No such file or directory"
-------------------------------------------------------------------------------
 The command prompt is pointing at the wrong folder.

 Fix: type "dir" and press Enter. You should see main.py in the list. If you
 do not, redo Step 2 - make sure File Explorer is showing the folder that
 contains main.py before you type "cmd" in the address bar.


 "This app requires Python 3.10 or newer" / odd syntax errors on startup
-------------------------------------------------------------------------------
 Your Python is too old. Check your version with:

       py --version

 If it shows anything below 3.10, install the current version from
 python.org using Step 1.


 The window opens but will not connect to 3CX
-------------------------------------------------------------------------------
 - Check the hostname has no "https://" at the front and no "/" at the end.
 - If your 3CX uses a non-standard port, add it, e.g. pbx.my3cx.us:5001
 - Confirm the same username and password work when you log in to the 3CX
   admin console in a web browser.
 - Read the error message shown in the program - it usually says whether
   the problem was the hostname, the credentials, or the two-factor code.


 It asks for a two-factor code every single time
-------------------------------------------------------------------------------
 The saved session is not being kept. Check that this folder is not
 read-only, and that "session_cache.json" can be created here. Running the
 program from inside a zip file without extracting it first will cause this.


===============================================================================
 See "version.txt" for the version history and what changed in each release.
===============================================================================
